Delete Label

Permanently delete a WhatsApp label.

DELETE

https://api.wawp.net/v2/labels/{labelId}?access_token=123456789&instance_id=123456789&labelId=3

Authentication Required

Test /v2/labels/{labelId}/delete endpoint

Supports

DELETE

No query parameters required

This endpoint doesn't expect data in the URL.

Cascade

Deleting a label removes it from ALL associated chats.

Irreversibility

This action cannot be undone.

Best practices

Consider renaming instead of deleting if the purpose changes slightly.
Merge chats into a new label before deleting the old one.

Lifecycle Management: The Deletion Protocol

The Delete Label endpoint is the final stage in a category's lifecycle. It allows you to prune obsolete categories from your global taxonomy, ensuring that your WhatsApp Business account remains focused and high-performing.

⚠️ The Gravity of Deletion: Irreversible Consequences

Deleting a label is one of the few truly destructive actions in the WhatsApp ecosystem. It is critical to understand the cascading effects before execution:

Global Taxonomy Removal: The label is purged from the account's directory. It will no longer appear in the Get All Labels response.
Automatic Untagging (The Cascade): Every conversation currently carrying this label will be stripped of it. This happens at the server level; you do not need to manually remove the label from individual chats before deleting the category.
Zero Recovery: There is no "Trash" or "Recycle Bin." Once a Label ID is deleted, it cannot be recovered. Recreating a label with the same name will result in a new ID, and previous chat associations will not be restored.

🚀 Strategic Operational Use Cases

1. Post-Campaign Decommissioning

Marketing efforts often use high-visibility labels (e.g., "Holiday Sale 2024") to track conversion. Once the campaign window closes and follow-ups are completed, deleting the label keeps the agent's sidebar clean and reduces cognitive load during daily operations.

2. Taxonomy Consolidation

As business processes evolve, you may find that multiple labels (e.g., "Web-Inquiry" and "Form-Inquiry") are essentially redundant. Deleting the surplus categories encourages agents to use a centralized, standardized "Digital Lead" tag instead.

3. Cleanup of Experimental Categories

When testing new automation flows or bot behaviors, you may create temporary labels for internal routing. Deleting these once testing is complete prevents your 20-label quota from being exhausted by "zombie" tags.

🛡️ The "Safe Decommissioning" Pattern

To avoid accidental data loss or workflow disruption, the following architectural steps should be taken before calling the Delete endpoint:

Usage Auditing: Always query Get Chats with Label to determine the volume of active threads currently relying on the tag.
Meta-Migration: If a label still has active threads, use a batch process to re-tag those chats with a replacement label (e.g., moving "Old Campaign" chats to "Generic Lead") before deleting the old category.
Cross-System Verification: Ensure that no external CRM filters or automated Slack notifications are exclusively triggered by the ID you are about to remove.

⚡ Integration Engineering & Webhooks

Orchestrating the "Untag" Flood

A single deletion event can trigger a massive number of state changes if the label was applied to thousands of chats.

Webhook Behavior: WhatsApp will fire the label.deleted event once. However, your system must be prepared for the fact that those chats no longer possess the metadata.
UI Reflex: Your application should immediately invalidate its label cache. If an agent's dashboard shows a "Deleted Label" badge, it may lead to confusion when they try to interact with that metadata and receive 404 errors from subsequent API calls.

🏗️ Enterprise Hygiene: Maximizing the 20-Label Limit

Because WhatsApp enforces a hard limit of 20 labels, deletion is a vital tool for "Metadata Grooming."

The "Garbage Collection" Rule: Develop a standard operating procedure (SOP) to review your labels every 30-90 days. Labels with zero active associations should be prioritized for deletion to make room for new initiatives.
Selective Lifecycle: Instead of creating permanent labels for every small event, reserve your IDs for high-level "Lifecycle States" (e.g., Lead, Customer, Escalated). Use deletion to rotate campaign-specific tags in and out of the available 20 slots.

🎯 Best Practices Summary

Read-Check-Delete: Always verify the label exists and check its usage count before pulling the trigger.
Inform Your Team: Deleting a label can be jarring for agents who rely on it for their daily triage. Coordinate with your support or sales leads before making taxonomy changes.
Update CRM References: Ensure your internal database is cleaned of any references to the deleted ID to prevent "Ghost Metadata" from appearing in your reports.
Favor Renaming (If Unsure): If you might need the label again, consider using the Update endpoint to rename it to "[DEPRECATED] Name" instead of deleting it immediately. This preserves the chat associations while signaling that the tag is out of rotation.

Request Parameters

Configure the parameters required to interact with this endpoint. All query and body arguments are listed below with their details.

Request Body

Sent as a JSON object

	`string`		Your unique WhatsApp Instance ID Example:
	`string`		Your API Access Token Example:
	`string`		The unique ID of the label to delete Example:

Request Samples

Use these ready-to-go code snippets to integrate our API into your project quickly and efficiently. Choose your preferred language and library.

1const baseUrl = "https://api.wawp.net";
2const endpoint = "/v2/labels/3";
3const params = new URLSearchParams({
4  "instance_id": "123456789",
5  "access_token": "123456789"
6}).toString();
7
8
9fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
10  method: "DELETE",
11  headers: { "Content-Type": "application/json" },
12  
13})
14  .then(async (response) => {
15    if (response.ok) {
16      const data = await response.json();
17      console.log("Success:", data);
18      return data;
19    }
20    
21    // Error Handling
22    if (response.status === 401) {
23      console.error("Error 401: Unauthorized - Invalid or Missing Access Token");
24    }
25    if (response.status === 500) {
26      console.error("Error 500: Internal Server Error - Unexpected Failure");
27    }
28
29    const errorText = await response.text();
30    console.error(`Error ${response.status}: ${errorText}`);
31  })
32  .catch((error) => console.error("Network Error:", error));

Interactive SamplesUTF-8

Ln 32, Col 1javascript

Expected Responses

Explore all possible responses and outcomes from the server. We have documented each status code with data examples to make success and error handling easier.

Label deleted successfully

application/json

boolean *

Example

{
"ok": true
}

Unauthorized - Invalid or Missing Access Token

Internal Server Error - Unexpected Failure